/**
 * @Date: Mar 3, 2010 1:56:32 PM
 */
package com.philip.journal.home.dao;

import java.util.List;
import java.util.Map;

import com.philip.journal.core.exception.JournalException;
import com.philip.journal.home.bean.Branch;

/**
 * @author cry30
 */
public interface BranchDAO {

    /**
     * Read all branches.
     *
     * @return empty list when no match is found.
     */
    List<Branch> readAll();

    /**
     * Read all branches under the specified parentId.
     *
     * @param parentId the branch id where to get the children Branches.
     *
     * @return empty list when no match is found.
     */
    List<Branch> readAllByParent(long parentId);

    /**
     * Read all objects with the given property matching the given value.
     *
     * @param property property name to match.
     * @param value value to match.
     * @return List of Branch that matches the given property name and value.
     *
     * @exception IllegalArgumentException If any of the following is true:
     *                <ul>
     *                <li>when the property passed is null.
     *                <li>when value type passed did not match the passed property.
     *                <li>when property passed does not exist.
     *                </ul>
     */
    List<Branch> readAllByProperty(String property, Object value);

    /**
     * Read the first object matching the given property-value pair in the given Map.
     *
     * @param param Map to match property name and value of the Branch.
     * @return The matching Branch otherwise null.
     */
    Branch readByProperty(Map<String, Object> param);

    /**
     * @param branchId - the id of the domain object to retrieve.
     * @return the domain object matching the specified id.
     */
    Branch read(long branchId);

    /**
     * Reads Branch by name.
     *
     * @param branchName name of the Branch.
     * @param parentId Branch ID of the parent.
     * @return object matching the name or null if it doesn't exist.
     */
    Branch readByName(String branchName, long parentId);

    /**
     * Persist a branch into the database. Will insert or update depending on the state of the passed bean.
     *
     * @param branch Branch entity object to persist.
     * @exception JournalException If any of the following is true:
     *                <ul>
     *                <li><code>object</code> passed has a non-existent primary key value.
     *                <li>null value on a not-null property constraint.
     *                </ul>
     *
     * @exception IllegalArgumentException when the object passed is null.
     */
    void save(Branch branch);

    /**
     * Deletes the list of branches.
     * 
     * @param branches List of Branches to delete.
     * @exception JournalException If any of the following is true:
     *                <ul>
     *                <li>when the object passed is null.
     *                <li>when one of the items in the listObj is null or is not a valid Branch.
     *                <li>foreign key constraint.
     *                <li>missing object for delete due to concurrency.
     *                </ul>
     */
    void deleteAll(List<Branch> branches);
}
